feat: data-attachment wrapper (Phase 2) - #13

Phase 2 of the pre-release storage/GUI plan: data-attachment wrapper

Wraps Common Storage Lib's DataManager so Archie mods can attach persistent (and optionally
synced) data to holders they don't own the class of — Entity, BlockEntity, ItemStack, and
(NeoForge only) ServerLevel — via a stateless, reusable object, complementing NBTHolder's
per-instance-owned field storage.

New API — net.kernelpanicsoft.archie.serialization.AttachmentRegistry/ArchieDataAttachment

object MyAttachments : AttachmentRegistry(MyMod.MOD_ID) {
    val mana by intAttachment(sync = true, default = { 0 })
}
var Entity.mana by MyAttachments.mana

// mod init:
MyAttachments.init()

• attachment(serializer, sync, copyOnDeath, itemComponent, default) (plus a reified variant and
  primitive convenience wrappers - intAttachment, stringAttachment, etc. - mirroring
  NBTHolder's field helpers).
• sync (reactive push to tracking players on every write) and itemComponent (vanilla
  DataComponentType-backed, rides normal item replication instead) are two genuinely different
  mechanisms - confirmed against both platforms' real DataManagerBuilderImpl source that
  itemComponent needs a client codec regardless of sync, since CSL's own builder breaks at
  registration time otherwise. Archie's wrapper always supplies one when needed, so this can't
  bite a consumer.
• Used directly (MyAttachments.mana.get(holder)/.set/.has/.remove/.modify) or as an
  extension-property delegate, as above.

A real platform quirk, found and documented (not dismissed)

get() on an unset Entity/BlockEntity/ServerLevel value silently creates and persists the
default - both Fabric's getAttachedOrCreate and NeoForge's getData write through on a miss.
That means has() can only tell "never touched" apart from "read once" if called before the
first get(). First surfaced as two real GameTest failures on Fabric; verified against Fabric's
actual attachment source rather than assumed, then documented in ArchieDataAttachment's KDoc and
docs/serialization.md, and the test suite now checks has() before get() accordingly.
ItemStack/itemComponent holders don't have this quirk.

Also confirmed (from CSL's real source, both platforms): ServerLevel sync is genuinely NeoForge-only

• Fabric's updateTarget dispatch has no Level case at all.

A real bug caught before it shipped

Returning ArchieDataAttachment<T> directly as a PropertyDelegateProvider's own delegate type
(since it itself implements ReadWriteProperty<Any?, T> so it can also back an extension
property) made val mana by intAttachment(...) unwrap straight through to T instead of binding
mana's type to the attachment object itself. Isolated via a standalone repro before touching the
real files; fixed by wrapping it in a plain ReadOnlyProperty, matching the existing pattern
NBTHolderImpl.itemField/fluidField/energyField already use for the same reason.

Verification

New DataAttachmentTests/DataAttachmentTestFixtures in Archie-Test, using vanilla
Entity/BlockEntity/ItemStack fixtures throughout (attachments are generic across holder kind,
unlike Phase 1's capability lookups, so no custom registered fixture type is needed). All 8 pass
under a real fabric-test:runGametest run:

[GameTest] PASS archie:dataattachmenttests.testblockentityattachmentroundtrip
[GameTest] PASS archie:dataattachmenttests.testextensionpropertydelegateroundtrip
[GameTest] PASS archie:dataattachmenttests.testgetreturnsdefaultbeforeset
[GameTest] PASS archie:dataattachmenttests.testitemcomponentattachmentroundtripsonitemstack
[GameTest] PASS archie:dataattachmenttests.testmodifyappliesfunctionandpersists
[GameTest] PASS archie:dataattachmenttests.testsetgethasremoveroundtrip
[GameTest] PASS archie:dataattachmenttests.testunexposeditemcomponentattachmentthrowsonitemstack
[GameTest] PASS archie:dataattachmenttests.testunsupportedholderthrowsillegalargumentexception

neoforge-test:runGametest currently registers zero real tests for any mod in this environment
(GameTestHooks: Enabled Gametest Namespaces: [], before any of this PR's code runs) - a
pre-existing NeoForge GameTest task/environment gap, not something introduced here (Phase 1 never
exercised that task either). NeoForge-specific behavior here is instead verified directly against
CSL's real NeoForge source (DataManagerImpl/DataManagerBuilderImpl), not just assumed
symmetric with Fabric.

Independent of Phase 1 (still open, unmerged) per the approved plan - this branches directly off
origin/1.21.x, so its test file uses plain fail(...) checks rather than Phase 1's not-yet-merged
public assertion helpers.

Part of the three-feature pre-release plan (capability lookup / data attachments / item-backed
container menus); Phase 3 to follow in a separate PR.

🤖 Generated with Claude Code